From: Peterson, John <[email protected]> 
Sent: Monday, September 23, 2024 2:54 PM
To: Kowalska, Kinga <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi Kinga,

This looks fine.

Thanks,
John

From: Kowalska, Kinga <[email protected]> 
Sent: Wednesday, September 18, 2024 7:21 AM
To: Peterson, John <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi John,

I thought the doc that we were incorporating into the README was addressing specifically this issue, that means, creating a web ready image with a client’s customized OS and JDK. Here’s what we have in the PR:

If you do not want to use the Pega-provided Docker image because, for example, you need a customized base image with your preferred OS and JDK enforced by a corporate standard, you can copy this repository and build your own pega-web-ready image based on your preferred base image. When making customizations for your environment, check the Pega Platform Support Guide Resources to verify that those changes are supported by your Pega Platform version.
Important: If you choose to build your own image, Pega will continue to offer support for Pega Platform, but problems that arise from your custom image are not the responsibility of Pegasystems.
To build a custom pega-web-ready image using your preferred OS and JDK, perform the following actions:
1.	Ensure that the base image you selected has $CATALINA_HOME set to the correct Tomcat location.
2.	Create a Dockerfile for your custom pega-web-ready image using your base image and the open-source pega-web-ready Dockerfile code.
For more information, see pegasystems/docker-pega-web-ready/Dockerfile.
Note: You can add any extra environment variables needed in the Dockerfile as per your use-case.
3.	Use the following command to build the custom pega-web-ready image using the base image as an argument.
   $ docker build --build-arg BASE_TOMCAT_IMAGE=<BASE_IMAGE> -t <IMAGE_NAME> .
The system then builds your custom pega-web-ready Docker image.
Do we need anything else?

If I’m not understanding this correctly, perhaps we could have a chat and clear this up? I could set up a meeting whenever you’re available.

Thank you!
Kinga

From: Peterson, John <[email protected]> 
Sent: Thursday, September 12, 2024 4:19 PM
To: Kowalska, Kinga <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

>>https://github.com/pegasystems/docker-pega-web-ready?tab=readme-ov-file#building-a-deployable-docker-image-using-this-web-ready-image
These instructions are for taking our provide pega-ready image to build a customized client image.   Again, as I explained below this is not really required anymore, because clients can simply take the Pega image to build their own customized client image.

I’m looking for the documentation that explains how clients could create a custom ready image with their own OS, JDK, and/or Tomcat implementation. 

John

From: Kowalska, Kinga <[email protected]> 
Sent: Thursday, September 12, 2024 9:55 AM
To: Peterson, John <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi John,

Do you mean a detailed explanation on how to use the Dockerfile? I thought all of the settings, building commands, image customizations, etc, were explained in the following sections of the readme? First in “Image customizations” and then https://github.com/pegasystems/docker-pega-web-ready?tab=readme-ov-file#building-a-deployable-docker-image-using-this-web-ready-image. Unless you mean something additional that was not covered?

Kinga

From: Peterson, John <[email protected]> 
Sent: Thursday, September 12, 2024 2:03 PM
To: Kowalska, Kinga <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi Kinga,

Yeah, I think that works.    Do we want to try to explain how they can achieve it?

John

From: Kowalska, Kinga <[email protected]> 
Sent: Wednesday, September 11, 2024 8:57 AM
To: Peterson, John <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi John,

Thank you for the detailed explanation, it was very illuminating. 😊

I propose that we write the following:

# Using this image

Pega offers a publicly available Pega runtime Docker image which includes the prweb.war file, but does not contain Pega rules - for details, see pegasystems/pega on DockerHub and Pega-provided Docker images. Pega builds the pegasystems/pega image from a pegasystems/pega-ready Docker image, a base image that contains an OS (Ubuntu Linux), a Java implementation (Adoptium Temurin JDK11 or JDK17), and an application server (Apache Tomcat) and is customized with Pega-specific configurations. You can use the pegasystems/pega-ready Dockerfile code to customize and build your own web-ready image and then extend it with the Pega .war file of your choice.
Docker images provided by Pegasystems are validated and supported by Pega Support.

Please let me know if this is sufficient.

Thanks!
Kinga


From: Peterson, John <[email protected]> 
Sent: Friday, September 6, 2024 6:20 PM
To: Kowalska, Kinga <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>; Talbot, Adam <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Is the Pegasystems/pega image the full Docker image, the same one we provide on our repo where you have to request an access token?
This is the runtime image.  It contains the .war file.  Yes, it can be obtained either via Dockerhub or from our repo with access token.   

Does this mean that we publicly provide the Docker image to install Pega Platform? 
The installer image is not available on Dockerhub and can only be obtained via downloads-pega.com with a valid access token.   The installer image contains the rules and code that need to be loaded into the database prior to starting the runtime image.

This discussion is specifically about the runtime image.   The runtime image is built on a pega-ready image.

The pega-ready image contains:

An operating system – Ubuntu Linux
A Java implimentation – Adoptium Temurin
An application server – Apache Tomcat
Pega specific configuration of Tomcat, Java, and Ubuntu.

The pega image adds:
The pega.war file.

At one point we thought it would be helpful to decouple the .war file from the ready image because the .war file was thought to be Pega Infinity agnostic.   The general idea was that a client would obtain the full distribution kit from PSOR, which contains the ‘version’ specific .war file.   They could run the installer scripts from the distro kit (this was before we even provided an installer image which does this for them).   Then then could ‘build’ their Pega image on top of the Ready image to include their Infinity .war file from the kit and any other configuration changes they would like to make (e.g. They may want to bake in their JDBC driver instead of downloading it at startup, and they may want to have a custom java.security policy, etc.).    At this time there was also no downloads.pega.com site/registry to obtain the Pega provided images.

Since that time the following things happened:
1)	We obtained approval to make the .war file available to Dockerhub.
2)	IT provided the downloads.pega.com site
3)	The .war file has been confirmed to be Infinity version agnostic.  
4)	There is a requirement by clients to provide their own OS, Java, & App Server.

Therefore, if the client just needs to bake in their own JDBC driver, java.security policy, or any other configuration, they can just use the Pega image.   The is no longer a reason for clients to use the Ready image (unless they are customizing the .war file itself – which I suppose is possible, but isn’t really supported by the platform)

If the client needs to change any or all of the third party open source software packaged inside the Pega image (the runtime image) like the OS, JDK, or Tomcat (e.g. switch to JBoss, Wildfly, or some enterprise Tomcat solution) then they need to be able to build their own Pega image.   To build their own image, they first need to build their own ‘ready’ image, thus the value of us providing the Dockerfile that shows how we do that.   Once they build their own ‘ready’ image, then they’ll need to layer on the .war, and other specific configurations (JDBC driver, etc.) to create their own Pega runtime image.

John


From: Kowalska, Kinga <[email protected]> 
Sent: Wednesday, August 28, 2024 5:57 AM
To: Peterson, John <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi John,

I don’t think I entirely follow the messaging. Is the Pegasystems/pega image the full Docker image, the same one we provide on our repo where you have to request an access token? Does this mean that we publicly provide the Docker image to install Pega Platform? 

If this is the same image, I’m confused about the difference between the .war file being in the Docker image and the Pega Platform rules being there.

Is this a four step process like this:

Tomcat image extended to  pega-web-ready which has preliminary rules but not the .war file and Pega Platform rules and extends to  Pegasystems/pega that has a .war file but not Pega Platform rules  platform/pega image available in the private repository with everything needed to deploy Pega Platform?

Thanks,
Kinga



From: Peterson, John <[email protected]> 
Sent: Tuesday, August 20, 2024 9:40 PM
To: Kowalska, Kinga <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi Kinga,  

I spoke to Dave Casavant, and we feel that since we are now providing a full “pega” image, there is no longer a need to mention the option of building from “pega-ready” outside of customization because clients could just take the “pega” image and not have to provide their own .war file.
It still provides value, because clients can see what needs to be done to build their own image if they don’t want to use ours.

So I’d update the following section to be something like (probably needs some word smithing)

# Using this image	 
		
		Pega offers a publicly available Docker image which includes the prweb.war file - for details, see [pegasystems/pega on DockerHub][pegasystems/pega].  It does not include Pega Platform rules.   The Pega image extends a web-ready Docker image.    The [pegasystems/pega-ready](https://hub.docker.com/r/pegasystems/pega-ready) Docker image extends a customized Tomcat base image with either JDK11 or JDK17 and contains required components that allow you to run a Pega Platform on your deployment nodes.  This ready image can be used as an example base image for clients who need to build a custom image.   Docker images provided by Pegasystems are validated and supported by [Pega Support](https://community.pega.com/support).

		
		
		
		
John

From: Kowalska, Kinga <[email protected]> 
Sent: Tuesday, August 20, 2024 6:11 AM
To: Peterson, John <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi John,

I created the following PR to move the doc to the readme:

#222

Please let me know if this is what you had in mind. I made some minor corrections to some links that weren’t working in the introduction as well.


Best regards,
Kinga Kowalska | Principal Technical Writer | Pegasystems Inc.
Email: [email protected] | pega.com
 
 



From: Peterson, John <[email protected]> 
Sent: Monday, August 19, 2024 2:14 PM
To: Kowalska, Kinga <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi Kinga,

I’m fine with you creating the PR, thanks!
Also, yes, I can review the new docs.pega.com article.

Thank you,
John

From: Kowalska, Kinga <[email protected]> 
Sent: Monday, August 19, 2024 8:03 AM
To: Peterson, John <[email protected]>; Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Hi John,

Perhaps it would be better if I created the pull request and integrated the current separate doc into the readme? This way I can quickly deal with commits and changes and you and Saurabh can approve the end product for technical accuracy. 

As for the docs.pega.com articles, I’m currently working on a global article that explains the Pega Git hub resources, which includes the Docker pega-web-ready repository. This additional article would be linked with the current information we have about custom images, which could be updated accordingly. Do you think you would be able to review the “Understanding Pega GitHub resources” article when it’s complete?

Thanks,
Kinga

From: Peterson, John <[email protected]> 
Sent: Monday, August 19, 2024 1:33 PM
To: Kumar, Saurabh <[email protected]>; Kowalska, Kinga <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: RE: Documentation to build custom runtime image.

Thank Saurabh,

Wow, I couldn’t find it.    I think the current location is hard to find and it is not referenced by any other document (that I could find).   To fix these issues, please move it to here:

https://github.com/pegasystems/docker-pega-web-ready/tree/aa3b38387e1604f174ea52ffa1d890a5f8abf182?tab=readme-ov-file#image-customizations

Kinga, can you review Saurabh’s PR when it’s ready?  We might need to update the wording of the intro to mention this new option.   Also the docs.pega.com references and mentions of custom images, could probably be reviewed as well, what do you think?

Thanks,
John

From: Kumar, Saurabh <[email protected]> 
Sent: Monday, August 19, 2024 1:10 AM
To: Peterson, John <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>; Saranathan, Raghu <[email protected]>
Subject: Re: Documentation to build custom runtime image.

Hi John,

Yes, the documentation can be accessed at  https://github.com/pegasystems/docker-pega-web-ready/blob/master/docs/Building-Image-With-Own-OS-And-JDK.md

-Saurabh

From: Peterson, John <[email protected]>
Date: Friday, 16 August 2024 at 11:32 PM
To: Kumar, Saurabh <[email protected]>
Cc: Chikkam, Venkata Satya Gopal <[email protected]>, Saranathan, Raghu <[email protected]>
Subject: Documentation to build custom runtime image.
Hi Saurabh,
 
As part of the FIPS work, in which we now publish detemplize as an image for usage by the builder pattern, did we ever update the image build documentation to explain how to bring your own OS & JDK?
 
John

BUG-883938 Move Build custom pega-web-ready doc to the main readme